/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package javax.servlet.http;

import java.util.Enumeration;

import javax.servlet.ServletRequest;

/**
 * 
 * Extends the {@link javax.servlet.ServletRequest} interface to provide request
 * information for HTTP servlets.
 * 
 * <p>
 * The servlet container creates an <code>HttpServletRequest</code> object and
 * passes it as an argument to the servlet's service methods (<code>doGet</code>,
 * <code>doPost</code>, etc).
 * 
 * 
 * @author Various
 * @version $Version$
 * 
 * 
 */

public interface HttpServletRequest extends ServletRequest {

	/**
	 * String identifier for Basic authentication. Value "BASIC"
	 */
	public static final String BASIC_AUTH = "BASIC";
	/**
	 * String identifier for Form authentication. Value "FORM"
	 */
	public static final String FORM_AUTH = "FORM";
	/**
	 * String identifier for Client Certificate authentication. Value
	 * "CLIENT_CERT"
	 */
	public static final String CLIENT_CERT_AUTH = "CLIENT_CERT";
	/**
	 * String identifier for Digest authentication. Value "DIGEST"
	 */
	public static final String DIGEST_AUTH = "DIGEST";

	/**
	 * Returns the name of the authentication scheme used to protect the
	 * servlet. All servlet containers support basic, form and client
	 * certificate authentication, and may additionally support digest
	 * authentication. If the servlet is not authenticated <code>null</code>
	 * is returned.
	 * 
	 * <p>
	 * Same as the value of the CGI variable AUTH_TYPE.
	 * 
	 * 
	 * @return one of the static members BASIC_AUTH, FORM_AUTH,
	 *         CLIENT_CERT_AUTH, DIGEST_AUTH (suitable for == comparison) or the
	 *         container-specific string indicating the authentication scheme,
	 *         or <code>null</code> if the request was not authenticated.
	 * 
	 */

	public String getAuthType();

	/**
	 * 
	 * Returns an array containing all of the <code>Cookie</code> objects the
	 * client sent with this request. This method returns <code>null</code> if
	 * no cookies were sent.
	 * 
	 * @return an array of all the <code>Cookies</code> included with this
	 *         request, or <code>null</code> if the request has no cookies
	 * 
	 * 
	 */

	public Cookie[] getCookies();

	/**
	 * 
	 * Returns the value of the specified request header as a <code>long</code>
	 * value that represents a <code>Date</code> object. Use this method with
	 * headers that contain dates, such as <code>If-Modified-Since</code>.
	 * 
	 * <p>
	 * The date is returned as the number of milliseconds since January 1, 1970
	 * GMT. The header name is case insensitive.
	 * 
	 * <p>
	 * If the request did not have a header of the specified name, this method
	 * returns -1. If the header can't be converted to a date, the method throws
	 * an <code>IllegalArgumentException</code>.
	 * 
	 * @param name
	 *            a <code>String</code> specifying the name of the header
	 * 
	 * @return a <code>long</code> value representing the date specified in
	 *         the header expressed as the number of milliseconds since January
	 *         1, 1970 GMT, or -1 if the named header was not included with the
	 *         request
	 * 
	 * @exception IllegalArgumentException
	 *                If the header value can't be converted to a date
	 * 
	 */

	public long getDateHeader(String name);

	/**
	 * 
	 * Returns the value of the specified request header as a
	 * <code>String</code>. If the request did not include a header of the
	 * specified name, this method returns <code>null</code>. If there are
	 * multiple headers with the same name, this method returns the first head
	 * in the request. The header name is case insensitive. You can use this
	 * method with any request header.
	 * 
	 * @param name
	 *            a <code>String</code> specifying the header name
	 * 
	 * @return a <code>String</code> containing the value of the requested
	 *         header, or <code>null</code> if the request does not have a
	 *         header of that name
	 * 
	 */

	public String getHeader(String name);

	/**
	 * 
	 * Returns all the values of the specified request header as an
	 * <code>Enumeration</code> of <code>String</code> objects.
	 * 
	 * <p>
	 * Some headers, such as <code>Accept-Language</code> can be sent by
	 * clients as several headers each with a different value rather than
	 * sending the header as a comma separated list.
	 * 
	 * <p>
	 * If the request did not include any headers of the specified name, this
	 * method returns an empty <code>Enumeration</code>. The header name is
	 * case insensitive. You can use this method with any request header.
	 * 
	 * @param name
	 *            a <code>String</code> specifying the header name
	 * 
	 * @return an <code>Enumeration</code> containing the values of the
	 *         requested header. If the request does not have any headers of
	 *         that name return an empty enumeration. If the container does not
	 *         allow access to header information, return null
	 * 
	 */

	public Enumeration getHeaders(String name);

	/**
	 * 
	 * Returns an enumeration of all the header names this request contains. If
	 * the request has no headers, this method returns an empty enumeration.
	 * 
	 * <p>
	 * Some servlet containers do not allow servlets to access headers using
	 * this method, in which case this method returns <code>null</code>
	 * 
	 * @return an enumeration of all the header names sent with this request; if
	 *         the request has no headers, an empty enumeration; if the servlet
	 *         container does not allow servlets to use this method,
	 *         <code>null</code>
	 * 
	 * 
	 */

	public Enumeration getHeaderNames();

	/**
	 * 
	 * Returns the value of the specified request header as an <code>int</code>.
	 * If the request does not have a header of the specified name, this method
	 * returns -1. If the header cannot be converted to an integer, this method
	 * throws a <code>NumberFormatException</code>.
	 * 
	 * <p>
	 * The header name is case insensitive.
	 * 
	 * @param name
	 *            a <code>String</code> specifying the name of a request
	 *            header
	 * 
	 * @return an integer expressing the value of the request header or -1 if
	 *         the request doesn't have a header of this name
	 * 
	 * @exception NumberFormatException
	 *                If the header value can't be converted to an
	 *                <code>int</code>
	 */

	public int getIntHeader(String name);

	/**
	 * 
	 * Returns the name of the HTTP method with which this request was made, for
	 * example, GET, POST, or PUT. Same as the value of the CGI variable
	 * REQUEST_METHOD.
	 * 
	 * @return a <code>String</code> specifying the name of the method with
	 *         which this request was made
	 * 
	 */

	public String getMethod();

	/**
	 * 
	 * Returns any extra path information associated with the URL the client
	 * sent when it made this request. The extra path information follows the
	 * servlet path but precedes the query string and will start with a "/"
	 * character.
	 * 
	 * <p>
	 * This method returns <code>null</code> if there was no extra path
	 * information.
	 * 
	 * <p>
	 * Same as the value of the CGI variable PATH_INFO.
	 * 
	 * 
	 * @return a <code>String</code>, decoded by the web container,
	 *         specifying extra path information that comes after the servlet
	 *         path but before the query string in the request URL; or
	 *         <code>null</code> if the URL does not have any extra path
	 *         information
	 * 
	 */

	public String getPathInfo();

	/**
	 * 
	 * Returns any extra path information after the servlet name but before the
	 * query string, and translates it to a real path. Same as the value of the
	 * CGI variable PATH_TRANSLATED.
	 * 
	 * <p>
	 * If the URL does not have any extra path information, this method returns
	 * <code>null</code> or the servlet container cannot translate the virtual
	 * path to a real path for any reason (such as when the web application is
	 * executed from an archive).
	 * 
	 * The web container does not decode this string.
	 * 
	 * 
	 * @return a <code>String</code> specifying the real path, or
	 *         <code>null</code> if the URL does not have any extra path
	 *         information
	 * 
	 * 
	 */

	public String getPathTranslated();

	/**
	 * 
	 * Returns the portion of the request URI that indicates the context of the
	 * request. The context path always comes first in a request URI. The path
	 * starts with a "/" character but does not end with a "/" character. For
	 * servlets in the default (root) context, this method returns "". The
	 * container does not decode this string.
	 * 
	 * 
	 * @return a <code>String</code> specifying the portion of the request URI
	 *         that indicates the context of the request
	 * 
	 * 
	 */

	public String getContextPath();

	/**
	 * 
	 * Returns the query string that is contained in the request URL after the
	 * path. This method returns <code>null</code> if the URL does not have a
	 * query string. Same as the value of the CGI variable QUERY_STRING.
	 * 
	 * @return a <code>String</code> containing the query string or
	 *         <code>null</code> if the URL contains no query string. The
	 *         value is not decoded by the container.
	 * 
	 */

	public String getQueryString();

	/**
	 * 
	 * Returns the login of the user making this request, if the user has been
	 * authenticated, or <code>null</code> if the user has not been
	 * authenticated. Whether the user name is sent with each subsequent request
	 * depends on the browser and type of authentication. Same as the value of
	 * the CGI variable REMOTE_USER.
	 * 
	 * @return a <code>String</code> specifying the login of the user making
	 *         this request, or <code>null</code> if the user login is not
	 *         known
	 * 
	 */

	public String getRemoteUser();

	/**
	 * 
	 * Returns a boolean indicating whether the authenticated user is included
	 * in the specified logical "role". Roles and role membership can be defined
	 * using deployment descriptors. If the user has not been authenticated, the
	 * method returns <code>false</code>.
	 * 
	 * @param role
	 *            a <code>String</code> specifying the name of the role
	 * 
	 * @return a <code>boolean</code> indicating whether the user making this
	 *         request belongs to a given role; <code>false</code> if the user
	 *         has not been authenticated
	 * 
	 */

	public boolean isUserInRole(String role);

	/**
	 * 
	 * Returns a <code>java.security.Principal</code> object containing the
	 * name of the current authenticated user. If the user has not been
	 * authenticated, the method returns <code>null</code>.
	 * 
	 * @return a <code>java.security.Principal</code> containing the name of
	 *         the user making this request; <code>null</code> if the user has
	 *         not been authenticated
	 * 
	 */

	public java.security.Principal getUserPrincipal();

	/**
	 * 
	 * Returns the session ID specified by the client. This may not be the same
	 * as the ID of the current valid session for this request. If the client
	 * did not specify a session ID, this method returns <code>null</code>.
	 * 
	 * 
	 * @return a <code>String</code> specifying the session ID, or
	 *         <code>null</code> if the request did not specify a session ID
	 * 
	 * @see #isRequestedSessionIdValid
	 * 
	 */

	public String getRequestedSessionId();

	/**
	 * 
	 * Returns the part of this request's URL from the protocol name up to the
	 * query string in the first line of the HTTP request. The web container
	 * does not decode this String. For example:
	 * 
	 * 
	 * 
	 * <table summary="Examples of Returned Values">
	 * <tr align=left>
	 * <th>First line of HTTP request </th>
	 * <th> Returned Value</th>
	 * <tr>
	 * <td>POST /some/path.html HTTP/1.1
	 * <td>
	 * <td>/some/path.html
	 * <tr>
	 * <td>GET http://foo.bar/a.html HTTP/1.0
	 * <td>
	 * <td>/a.html
	 * <tr>
	 * <td>HEAD /xyz?a=b HTTP/1.1
	 * <td>
	 * <td>/xyz </table>
	 * 
	 * <p>
	 * To reconstruct an URL with a scheme and host, use
	 * {@link HttpUtils#getRequestURL}.
	 * 
	 * @return a <code>String</code> containing the part of the URL from the
	 *         protocol name up to the query string
	 * 
	 * @see HttpUtils#getRequestURL
	 * 
	 */

	public String getRequestURI();

	/**
	 * 
	 * Reconstructs the URL the client used to make the request. The returned
	 * URL contains a protocol, server name, port number, and server path, but
	 * it does not include query string parameters.
	 * 
	 * <p>
	 * Because this method returns a <code>StringBuffer</code>, not a string,
	 * you can modify the URL easily, for example, to append query parameters.
	 * 
	 * <p>
	 * This method is useful for creating redirect messages and for reporting
	 * errors.
	 * 
	 * @return a <code>StringBuffer</code> object containing the reconstructed
	 *         URL
	 * 
	 */
	public StringBuffer getRequestURL();

	/**
	 * 
	 * Returns the part of this request's URL that calls the servlet. This path
	 * starts with a "/" character and includes either the servlet name or a
	 * path to the servlet, but does not include any extra path information or a
	 * query string. Same as the value of the CGI variable SCRIPT_NAME.
	 * 
	 * <p>
	 * This method will return an empty string ("") if the servlet used to
	 * process this request was matched using the "/*" pattern.
	 * 
	 * @return a <code>String</code> containing the name or path of the
	 *         servlet being called, as specified in the request URL, decoded,
	 *         or an empty string if the servlet used to process the request is
	 *         matched using the "/*" pattern.
	 * 
	 */

	public String getServletPath();

	/**
	 * 
	 * Returns the current <code>HttpSession</code> associated with this
	 * request or, if there is no current session and <code>create</code> is
	 * true, returns a new session.
	 * 
	 * <p>
	 * If <code>create</code> is <code>false</code> and the request has no
	 * valid <code>HttpSession</code>, this method returns <code>null</code>.
	 * 
	 * <p>
	 * To make sure the session is properly maintained, you must call this
	 * method before the response is committed. If the container is using
	 * cookies to maintain session integrity and is asked to create a new
	 * session when the response is committed, an IllegalStateException is
	 * thrown.
	 * 
	 * 
	 * 
	 * 
	 * @param create
	 *            <code>true</code> to create a new session for this request
	 *            if necessary; <code>false</code> to return <code>null</code>
	 *            if there's no current session
	 * 
	 * 
	 * @return the <code>HttpSession</code> associated with this request or
	 *         <code>null</code> if <code>create</code> is
	 *         <code>false</code> and the request has no valid session
	 * 
	 * @see #getSession()
	 * 
	 * 
	 */

	public HttpSession getSession(boolean create);

	/**
	 * 
	 * Returns the current session associated with this request, or if the
	 * request does not have a session, creates one.
	 * 
	 * @return the <code>HttpSession</code> associated with this request
	 * 
	 * @see #getSession(boolean)
	 * 
	 */

	public HttpSession getSession();

	/**
	 * 
	 * Checks whether the requested session ID is still valid.
	 * 
	 * @return <code>true</code> if this request has an id for a valid session
	 *         in the current session context; <code>false</code> otherwise
	 * 
	 * @see #getRequestedSessionId
	 * @see #getSession
	 * @see HttpSessionContext
	 * 
	 */

	public boolean isRequestedSessionIdValid();

	/**
	 * 
	 * Checks whether the requested session ID came in as a cookie.
	 * 
	 * @return <code>true</code> if the session ID came in as a cookie;
	 *         otherwise, <code>false</code>
	 * 
	 * 
	 * @see #getSession
	 * 
	 */

	public boolean isRequestedSessionIdFromCookie();

	/**
	 * 
	 * Checks whether the requested session ID came in as part of the request
	 * URL.
	 * 
	 * @return <code>true</code> if the session ID came in as part of a URL;
	 *         otherwise, <code>false</code>
	 * 
	 * 
	 * @see #getSession
	 * 
	 */

	public boolean isRequestedSessionIdFromURL();

	/**
	 * 
	 * @deprecated As of Version 2.1 of the Java Servlet API, use
	 *             {@link #isRequestedSessionIdFromURL} instead.
	 * 
	 */

	public boolean isRequestedSessionIdFromUrl();

}
